IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / Vk / VkSimpleWindow.z / VkSimpleWindow

Wrap

Text File | 2001-04-17 | 45.6 KB | 1,057 lines

VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) NNNNAAAAMMMMEEEE VkSimpleWindow - Base class for all top-level windows IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM VkComponent : VkCallbackObject HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <Vk/VkSimpleWindow.h> PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr VkSimpleWindow(const char *name, ArgList args = NULL, Cardinal argCount = 0); virtual ~VkSimpleWindow(); CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkSimpleWindow(const char *name, VkScreen *screen, ArgList args = NULL, Cardinal argCount = 0); AAAAddddddddiiiinnnngggg aaaannnndddd RRRReeeemmmmoooovvvviiiinnnngggg VVVViiiieeeewwwwssss void addView(Widget w); void addView(VkComponent *comp); void removeView(); MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg WWWWiiiinnnnddddoooowwwwssss virtual void open(); virtual void raise(); virtual void lower(); virtual void iconify(); virtual void show(); virtual void hide(); WWWWiiiinnnnddddoooowwww MMMMaaaannnnaaaaggggeeeerrrr IIIInnnntttteeeerrrrffffaaaacccceeeessss const char *getTitle(); void setTitle(const char *newTitle); void setIconName(const char *newName); void setClassHint(const char *className); AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss virtual const char* className(); int getVisualState() Boolean iconic() Boolean visible() static VkSimpleWindow *getWindow(VkComponent *component); PPPPaaaaggggeeee 1111 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkScreen *getScreen(); SSSSUUUUBBBBCCCCLLLLAAAASSSSSSSS PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY WWWWiiiinnnnddddoooowwww SSSSttttaaaatttteeee enum IconState { OPEN, CLOSED, ICON_UNKNOWN }; enum VisibleState { HIDDEN, VISIBLE, VISIBLE_UNKNOWN }; enum StackingState{ RAISED, LOWERED, STACKING_UNKNOWN}; IconState _iconState; VisibleState _visibleState; StackingState _stackingState; WWWWiiiiddddggggeeeetttt AAAAcccccccceeeessssssss Widget _mainWindowWidget; virtual Widget mainWindowWidget() const; virtual Widget viewWidget() const; virtual operator Widget () const; AAAAddddddddiiiinnnngggg VVVViiiieeeewwwwssss virtual Widget setUpInterface(Widget parent); SSSSuuuubbbbccccllllaaaassssssss HHHHooooooookkkkssss virtual void setUpWindowProperties(); virtual void stateChanged(IconState); virtual void handleWmDeleteMessage(); virtual void handleWmQuitMessage(); virtual void handleRawEvent(XEvent *event); virtual void afterRealizeHook(); CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The VkSimpleWindow class implements a simple top-level window to be used by ViewKit applications. The VkSimpleWindow is intended for use when a menu bar is not desired. Instantiating a VkSimpleWindow object creates a popup shell widget as a child of the shell supported by an instance of VkApp, which must already exist. VkSimpleWindow also creates a Motif XmMainWindow widget as a child of the shell. Applications must create a widget to be used as the work area, or "view" contained by the XmMainWindow. By default, the XmMainWindow is configured to not display scrollbars, and no other areas of the XmMainWindow widget, besides the work area, are used. Applications, or subclasses, can access the main window to configure it however they would like. Menus are supported by the VkWindow class. In addition to creating a shell and an XmMainWindow, the VkSimpleWindow class registers itself with the application's VkApp instance, sets up various properties on the shell window, and provides simple hooks for applications that need to handle window manager interactions. For PPPPaaaaggggeeee 2222 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) example, all windows support operations to raise, lower, iconify, and open windows by calling a single member function. Each window also maintains its current state, so it is straightforward to find out whether or a not a given window is iconified, or whether is it is currently visible. The class also supports the user's ability to close a window using the window manager. (See the handleWmDeleteMessage() and handleWmQuitMessage() methods.) The VkSimpleWindow class works together with VkApp to provide application-wide services such as displaying cursors in all windows, entering busy states, and manipulating all windows in an application. AAAAddddddddiiiinnnngggg aaaa VVVViiiieeeewwww By itself, the VkSimpleWindow class simply provides a framework for a window. The contents of the window must be defined by the application. This can be done in one of several ways. In most cases, it is best to define a subclass of VkSimpleWindow in which to add the view, along with handling other supporting operations and data. In some cases, it may be useful to add a view directly to a VkSimpleWindow instance, without deriving a new class. QQQQuuuuiiiicccckkkkHHHHeeeellllpppp _Q_u_i_c_k_H_e_l_p is a facility that displays a (presumably helpful) string when the pointer enters a widget. Help can be displayed in a message line at the bottom of the application, in a small window that pops up next to the pointer (i.e., "balloon help" or "popup help"), or both ways. Each way can have its own help text -- perhaps a brief phrase for popup help, and a more detailed message for the message line. QuickHelp availability is controlled by the resources _s_h_o_w_H_e_l_p, _s_h_o_w_P_o_p_u_p_H_e_l_p, and _s_h_o_w_M_s_g_L_i_n_e_H_e_l_p. These resources must be set when the VkSimpleWindow is created. QuickHelp cannot be created later, though the programmatic interface allows it to be activated and de-activated. If _s_h_o_w_H_e_l_p is FFFFAAAALLLLSSSSEEEE, then no QuickHelp will be shown. This provides an easy way to enable or disable the entire QuickHelp system. If _s_h_o_w_P_o_p_u_p_H_e_l_p is FFFFAAAALLLLSSSSEEEE, there will be no popup help. If it is TTTTRRRRUUUUEEEE, there will be popup help if, and only if, _s_h_o_w_H_e_l_p is also TTTTRRRRUUUUEEEE. Popup help is a good way to solve the problem of ensuring that a user understands what a button displaying a pixmap is really for. If _s_h_o_w_M_s_g_L_i_n_e_H_e_l_p is FFFFAAAALLLLSSSSEEEE, there will be no message line help. If it is TTTTRRRRUUUUEEEE, there will be message line help if, and only if, _s_h_o_w_H_e_l_p is also TTTTRRRRUUUUEEEE. Space will be allocated for message line help at the bottom of the window only if message line help is enabled. PPPPaaaaggggeeee 3333 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) QuickHelp usability includes getting balloons promptly when you want them, but not getting them when you do not want them. This is a DWIM (Do What I Mean) problem, and so has no perfect solution. In an attempt to come as close as we can, QuickHelp has a several timers. These timings greatly affect the usability of QuickHelp, so you should not generally alter them. However, if you do not like the default timings, you can adjust them to suit yourself. A full discussion of these timers is beyond the scope of this man page, but here are the ones that are available: _h_e_l_p_T_e_x_t_B_r_o_w_s_e_C_a_n_c_e_l_T_i_m_e -- the length of time after leaving a widget before browse mode is canceled. _h_e_l_p_T_e_x_t_B_r_o_w_s_e_W_a_i_t_T_i_m_e -- the delay after entering a widget, when in browse mode, before the QuickHelp balloon will be posted. _h_e_l_p_T_e_x_t_B_r_o_w_s_e_V_e_l_o_c_i_t_y -- the velocity below which a QuickHelp balloon should be posted as you browse, and above which you are just in transit. If you are just in transit, then no balloon will be posted. _h_e_l_p_T_e_x_t_W_a_i_t_T_i_m_e -- the delay after entering a widget, when not in browse mode, before the QuickHelp balloon will be posted. _h_e_l_p_T_e_x_t_T_i_m_e_U_p -- the length of time a QuickHelp balloon will remain posted. There are some miscellaneous resources: _h_e_l_p_T_e_x_t_I_n_s_e_n_s_i_t_i_v_e -- controls whether or not QuickHelp is given when entering insensitive widgets. _s_m_a_l_l_W_i_d_g_e_t -- this is the size of the minor dimension of a "wide" of a "tall" widget. This is used to determine whether a QuickHelp balloon goes below a widget, or whether it should be posted beside the widget. For example, if you have a vertical scrollbar that has QuickHelp, you would probably want QuickHelp to the right of the scrollbar, not below it. There are two resources intended for developers and for debugging, but which may also be useful to some end-users. _d_u_m_p_T_r_e_e prints the name and class for each of the widgets in the widget tree when the VkSimpleWindow is created. This can be useful as a starting point for creating the QuickHelp text for each widget. NOTE: A common error is to forget that this cannot dump any widget that is not yet created. For example, unless you have disabled it, ViewKit created menus later (in a workProc). That means they will not get included in the widget tree that is dumped. PPPPaaaaggggeeee 4444 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) _s_h_o_w_W_i_d_g_e_t_I_n_f_o causes QuickHelp to display the widget name, rather than any QuickHelp text. The information displayed this way may be expanded in a future release. This can be useful when trying to figure out just what a widget is called so you can set a resource for it. And, finally, there are two per-widget resources that provide the actual help strings, _m_s_g_L_i_n_e_H_e_l_p_T_e_x_t and _p_o_p_u_p_H_e_l_p_T_e_x_t. Both of these are of resource class _Q_u_i_c_k_H_e_l_p_T_e_x_t. If any widget does not have one of these resources set, it will not get that kind of help, regardless of any global settings. There is also a programmatic interface to QuickHelp. This interface is still experimental, so it may change in incompatible ways in a future release. When it becomes a supported permanent ABI, it will be documented here. If you need to use it in the meantime, see the header files and the QuickHelp ViewKit demo program for information. DDDDeeeerrrriiiivvvviiiinnnngggg SSSSuuuubbbbccccllllaaaasssssssseeeessss It is best to add a view (or work area) in which to display an application-specific interface in a subclass. The view can be added in one of two ways. The first way is to create a widget, or a component in the subclass constructor, and to call addView(). A VkSimpleWindow supports only a single child widget. The following example derived class adds a Motif XmLabel widget as a view. The XmLabel widget is created as a child of the XmMainWindow (accessed through the mainWindowWidget() member function inherited from VkSimpleWindow). More complex examples might create entire widget hierarchies. Real examples also seldom declare the constructor inline, as shown here. #include <Vk/VkApp.h> #include <Vk/VkSimpleWindow.h> #include <Xm/Label.h> class SampleWindow: public VkSimpleWindow { public: SampleWindow ( const char *name ) : VkSimpleWindow ( name ) { Widget label = XmCreateLabel ( mainWindowWidget(), "sample", NULL, 0 ); addView(label); } }; PPPPaaaaggggeeee 5555 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) It is recommended that applications be designed so that the view added to a VkSimple window is a component. (See VkComponent(3X).) This approach works the same as that demonstrated above. For example, the following example creates a VkRadioBox component and installs several items. (See VkRadioBox(3X).) #include <Vk/VkApp.h> #include <Vk/VkSimpleWindow.h> #include <Vk/VkRadioBox.h> class SampleWindow: public VkSimpleWindow { public: SampleWindow ( const char *name ) : VkSimpleWindow ( name ) { VkRadioBox *rb = new VkRadioBox("check", mainWindowWidget()); rb->addItem("one"); rb->addItem("two"); rb->addItem("three"); rb->addItem("four"); addView(rb); } }; Some applications may wish to delay the creation of an interface until the window is ready to be displayed. In this case, a subclass of VkSimpleWindow can be created without adding a view in the constructor. Instead, a virtual method, setUpInterface() can be defined. This method is called when the component is displayed (as a result of a call to show()) if no view has been added. This method supplies the main window widget to be used as the parent of the window's widget hierarchy as an argument. The setUpInterface() method is expected to return a widget to be added as a view. Using this approach,the above example can be written as follows: #include <Vk/VkApp.h> #include <Vk/VkSimpleWindow.h> #include <Vk/VkRadioBox.h> class SampleWindow: public VkSimpleWindow { protected: Widget setUpInterface(Widget parent) { PPPPaaaaggggeeee 6666 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VkRadioBox *rb = new VkRadioBox("check", parent); rb->addItem("one"); rb->addItem("two"); rb->addItem("three"); rb->addItem("four"); return (rb->baseWidget()); // Could also be: return ((Widget) *rb); } public: SampleWindow ( const char *name ) : VkSimpleWindow ( name ) {}; }; FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww(((()))) VkSimpleWindow(const char *name, ArgList argList = NULL, Cardinal argCount = 0); Create a VkSimpleWindow object. This function creates a popup shell and a Motif XmMainWindow widget, and sets up various properties and callbacks needed for window manager interaction. The window is also registered with the current application object. VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww(((()))) ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkSimpleWindow(const char *name, VkScreen *screen, ArgList argList = NULL, Cardinal argCount = 0); Create a VkSimpleWindow object on the specified VkScreen. This function creates a popup shell and a Motif XmMainWindow widget, and sets up various properties and callbacks needed for window manager interaction. The window is also registered with the specified VkScreen object. ~~~~VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww(((()))) virtual ~VkSimpleWindow(); The destructor deletes any privately allocated data and removes the window from the current application's list of windows. The VkComponent destructor destroys the widgets used in this class. PPPPaaaaggggeeee 7777 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) ggggeeeettttSSSSccccrrrreeeeeeeennnn(((()))) ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkScreen *getScreen(); Returns the VkScreen object associated with this window. aaaaddddddddVVVViiiieeeewwww(((()))) void addView(Widget w); void addView(VkComponent *comp); Add a widget or a component as the window's work area, or view. There can be only one view at any given time. However, views can be changed by removing a view and then adding a new view. (See also VkDeck(3X), which supports stacks of widgets or components.) rrrreeeemmmmoooovvvveeeeVVVViiiieeeewwww(((()))) void removeView(); Remove the current view from the screen. This function should not be called unless a view has been previously added. The view (Widget or component) is not destroyed. ooooppppeeeennnn(((()))) virtual void open(); If the VkSimpleWindow object is in an iconified state, the window is changed to an un-iconified state. This does not affect whether or not the window is actually visible. It may still be _h_i_d_d_e_n, or not hidden but another window may be on top of it. See _W_I_N_D_O_W _S_T_A_T_E_S, below. rrrraaaaiiiisssseeee(((()))) virtual void raise(); Raise the window to the top of the screen. lllloooowwwweeeerrrr(((()))) virtual void lower(); Lower the window to the bottom of the screen. iiiiccccoooonnnniiiiffffyyyy(((()))) virtual void iconify(); PPPPaaaaggggeeee 8888 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) If the VkSimpleWindow object is in a normal state, the window is changed to an iconified state. This does not affect whether or not the icon is actually visible. It may still be _h_i_d_d_e_n, or not hidden but another window may be on top of it. See _W_I_N_D_O_W _S_T_A_T_E_S, below. sssshhhhoooowwww(((()))) virtual void show(); If a window is currently in a hidden state, display the window. This does not affect whether or not the window is iconic. It also does not affect whether or not the window is actually visible - another window may be on top of it. See _W_I_N_D_O_W _S_T_A_T_E_S, below. hhhhiiiiddddeeee(((()))) virtual void hide(); If the window or icon is currently visible, it is removed from the screen. This does not affect whether or not the window is considered iconic. See _W_I_N_D_O_W _S_T_A_T_E_S, below. ggggeeeettttTTTTiiiittttlllleeee const char *getTitle(); Return the current title of the window as a string. sssseeeettttTTTTiiiittttlllleeee void setTitle(const char *newTitle); Set the current title of the window. This string is treated first as the name of a resource that indicates a title. If no such resource is found, the string is used as the title itself. This allows applications to dynamically change a window title, without necessarily hard-coding the exact title names in the application code. sssseeeettttIIIIccccoooonnnnNNNNaaaammmmeeee void setIconName(const char *newName); Set the current title of the window's icon. This string is treated first as the name of a resource that indicates a title. If no such resource is found, the string is used as the icon title itself. This allows applications to dynamically change an icon's title, without necessarily hard-coding the exact icon names in the application code. PPPPaaaaggggeeee 9999 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) sssseeeettttCCCCllllaaaassssssssHHHHiiiinnnnttttssss(((()))) void setClassHint(const char *className); Changes the value of the window manager class hint stored on this window. ccccllllaaaassssssssNNNNaaaammmmeeee virtual const char* className(); The class name of VkSimpleWindow is "VkSimpleWindow". ggggeeeettttVVVViiiissssuuuuaaaallllSSSSttttaaaatttteeee int getVisualState(); This returns the X11 window state, as specified by the ICCCM (sections 4.1.2.4, 4.1.4), with one extension. The ICCCM specifies states _W_i_t_h_d_r_a_w_n_S_t_a_t_e, _N_o_r_m_a_l_S_t_a_t_e, and _I_c_o_n_i_c_S_t_a_t_e. In actual fact, when an unmapped window is mapped, it may come back as either _N_o_r_m_a_l or _I_c_o_n_i_c. In recognition of this ViewKit adds the corresponding states: WWWWiiiitttthhhhddddrrrraaaawwwwnnnnNNNNoooorrrrmmmmaaaallllSSSSttttaaaatttteeee is the same as _W_i_t_h_d_r_a_w_n_S_t_a_t_e. Both mean that the window will be in _N_o_r_m_a_l_S_t_a_t_e when it gets mapped. WWWWiiiitttthhhhddddrrrraaaawwwwnnnnIIIIccccoooonnnniiiiccccSSSSttttaaaatttteeee is new. It means that the window will be in _I_c_o_n_i_c_S_t_a_t_e when it gets mapped. iiiiccccoooonnnniiiicccc Boolean iconic() Returns TRUE if the window is currently in an iconic state. Returns FALSE if the window is currently in a normalized state. This is unrelated to whether or not the window or icon is actually visible. It may still be _h_i_d_d_e_n, or not hidden but another window may be on top of it. See _W_I_N_D_O_W _S_T_A_T_E_S, below. vvvviiiissssiiiibbbblllleeee(((()))) Boolean visible() Returns TRUE if the window is not hidden (i.e., the window or icon is mapped). This is unrelated to whether or not the window or icon is actually visible on the screen. It may still be _h_i_d_d_e_n, or not PPPPaaaaggggeeee 11110000 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) hidden but another window may be on top of it. See _W_I_N_D_O_W _S_T_A_T_E_S, below. ggggeeeettttWWWWiiiinnnnddddoooowwww(((()))) static VkSimpleWindow *getWindow(VkComponent *component); Returns the VkSimpleWindow object (or subclass) that contains the given VkComponent. This allows components to operate on the window in which they are contained without a hard coded connection between the window and the component. WWWWiiiinnnnddddoooowwww SSSSttttaaaatttteeee VVVVaaaalllluuuueeeessss enum IconState { OPEN, CLOSED, ICON_UNKNOWN }; enum VisibleState { HIDDEN, VISIBLE, VISIBLE_UNKNOWN }; enum StackingState { RAISED, LOWERED, STACKING_UNKNOWN }; These values are used to track the window's state. These values are available to subclasses only. ____iiiiccccoooonnnnSSSSttttaaaatttteeee IconState _iconState; This member is kept up-to-date with the current state of the window, which will be one of OPEN, CLOSED, or ICON_UNKNOWN. This state is independent of the value of other states. ____vvvviiiissssiiiibbbblllleeeeSSSSttttaaaatttteeee VisibleState _visibleState; This member will be set to HIDDEN if the window is not visible and VISIBLE if it is. This state is independent of the value of other states. ____ssssttttaaaacccckkkkiiiinnnnggggSSSSttttaaaatttteeee StackingState _stackingState; This member will be set to RAISED if the window has been raised to the top of other windows, and LOWERED if it has been lowered below its siblings. mmmmaaaaiiiinnnnWWWWiiiinnnnddddoooowwwwWWWWiiiiddddggggeeeetttt virtual Widget mainWindowWidget() const; This function returns the XmMainWindow widget created by the VkSimpleWindow. PPPPaaaaggggeeee 11111111 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) vvvviiiieeeewwwwWWWWiiiiddddggggeeeetttt virtual Widget viewWidget() const; Returns the widget currently installed as a view. sssseeeettttUUUUppppIIIInnnntttteeeerrrrffffaaaacccceeee virtual Widget setUpInterface(Widget parent); If no view has been added by the time a VkSimpleWindow needs to display itself (because show() has been called), setUpInterface() is called. This function is expected to create and return a widget as a child of the specified parent. Using this function has the same effect as calling addView, but the widgets are not created until the window is about to be displayed. sssseeeettttUUUUppppWWWWiiiinnnnddddoooowwwwPPPPrrrrooooppppeeeerrrrttttiiiieeeessss virtual void setUpWindowProperties(); This function is called after a VkSimpleWindow object's shell widget is realized. It initializes the properties involved in the window manager's WM_DELETE protocol. Derived classes that wish to store other properties on the window can override this function and perform additional actions. If this function is overridden, the function belonging to the base class should be called from the derived class function. ssssttttaaaatttteeeeCCCChhhhaaaannnnggggeeeedddd virtual void stateChanged(IconState); This function is called when the window's iconic state changes. Derived classes that need to know when these transitions occur can override this function. Because this function is responsible for maintaining the objects state information, functions defined by a derived class should always call the base class function before performing any desired additional operations. hhhhaaaannnnddddlllleeeeWWWWmmmmDDDDeeeelllleeeetttteeeeMMMMeeeessssssssaaaaggggeeee(((()))) virtual void handleWmDeleteMessage(); This function is called when the user closes a window using the window manager. (For example, the Motif Window manager, mwm, supports a Close menu entry for each window.) The default action of this function is to delete the object. Derived class that wish to change this behavior can override this function. Derived classes that simply wish to perform additional actions before the object is deleted can override the function, perform the required actions, and then call the base class function. PPPPaaaaggggeeee 11112222 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) hhhhaaaannnnddddlllleeeeWWWWmmmmQQQQuuuuiiiittttMMMMeeeessssssssaaaaggggeeee(((()))) virtual void handleWmQuitMessage(); This function is called when the user quits an application using the 4Dwm window manager extension to the ICCCM protocol. The default action of this function is to call VkApp::quitYourself(). Derived class that wish to change this behavior can override this function. Derived classes that simply wish to perform additional actions before the object is deleted can override the function, perform the required actions, and then call the base class function. hhhhaaaannnnddddlllleeeeRRRRaaaawwwwEEEEvvvveeeennnntttt virtual void handleRawEvent(XEvent *event); Some events that may be received by an application are not dispatched by the Xt dispatch mechanism. For example, propertyNotify on windows other than Motif widgets cannot be dispatched. When such an event is received by the VkApp event loop, the event is dispatched to all top-level windows by calling each window's handleRawEvent() member function. The default function is empty. Derived classes that wish to handle the event should override this function. aaaafffftttteeeerrrrRRRReeeeaaaalllliiiizzzzeeeeHHHHooooooookkkk virtual void afterRealizeHook(); This function is called immediately after a VkSimpleWindow object's shell widget is realized. Derived classes that need to perform certain actions only after a window exists can override this function. WWWWIIIINNNNDDDDOOOOWWWW SSSSTTTTAAAATTTTEEEESSSS In X11, there are three possible window states: NNNNoooorrrrmmmmaaaallllSSSSttttaaaatttteeee Only the application's _V_k_S_i_m_p_l_e_W_i_n_d_o_w is mapped. IIIIccccoooonnnniiiiccccSSSSttttaaaatttteeee Only the application's icon is mapped. WWWWiiiitttthhhhddddrrrraaaawwwwnnnnSSSSttttaaaatttteeee Neither the application's window nor its icon is mapped. To clarify two possible meanings of _W_i_t_h_d_r_a_w_n_S_t_a_t_e, VkSimpleWindow adds the following states: PPPPaaaaggggeeee 11113333 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) WWWWiiiitttthhhhddddrrrraaaawwwwnnnnNNNNoooorrrrmmmmaaaallllSSSSttttaaaatttteeee Is the same as _W_i_t_h_d_r_a_w_n_S_t_a_t_e. Both mean that when the window is mapped, it will be in _N_o_r_m_a_l_S_t_a_t_e. WWWWiiiitttthhhhddddrrrraaaawwwwnnnnIIIIccccoooonnnniiiiccccSSSSttttaaaatttteeee Means that when the window is mapped, it will be in _I_c_o_n_i_c_S_t_a_t_e. A window's state is unrelated to whether or not the actual window is in fact visible on the screen. A window can be in either _N_o_r_m_a_l_S_t_a_t_e or _I_c_o_n_i_c_S_t_a_t_e, and still not be visible if it is obscured by another window on top of it. A window starts out in _W_i_t_h_d_r_a_w_n_S_t_a_t_e (ICCCM 4.1.1, 4.1.2.4). The window manager, possibly cooperating with a session manager, then transitions the window to either _N_o_r_m_a_l_S_t_a_t_e or _I_c_o_n_i_c_S_t_a_t_e. This means that there is no way for an application to know in advance what the initial state of a window will be. The application must either: +o wait until the window is no longer in _W_i_t_h_d_r_a_w_n_S_t_a_t_e and then see what the actual state is. +o force the initial state. Because it defeats session management, this is generally a Bad Thing to do. VkSimpleWindow allows independent control over the iconic state of a window and whether or not it is actually mapped. These aspects are independent of each other. MMMMaaaappppppppiiiinnnngggg aaaa wwwwiiiinnnnddddoooowwww A window must be mapped to be visible. If mapped, the application's window or icon will actually be visible only if it is within the screen area and not obscured by another window. _s_h_o_w() maps the window or icon, _h_i_d_e() unmaps it, and _v_i_s_u_a_l() tells whether or not it is mapped. IIIIccccoooonnnniiiiffffyyyyiiiinnnngggg aaaa wwwwiiiinnnnddddoooowwww An application is visually represented by either its window or its icon. If it is represented by its icon, the application's actual window will be unmapped, and therefore invisible. Whether or not the icon is visible is determined by whether it is mapped. This means that _i_c_o_n_i_c() does not tell anything about whether or not the actual window or icon is visible. _I_c_o_n_i_f_y() iconifies a window, _o_p_e_n() un-iconifies it, and _i_c_o_n_i_c() tells whether or not the window is iconified. ggggeeeettttVVVViiiissssuuuuaaaallllSSSSttttaaaatttteeee(((()))) allows an application to tell, with a single call, which state the application is in: _W_i_t_h_d_r_a_w_n_N_o_r_m_a_l_S_t_a_t_e, _W_i_t_h_d_r_a_w_n_I_c_o_n_i_c_S_t_a_t_e, _N_o_r_m_a_l_S_t_a_t_e, or _I_c_o_n_i_c_S_t_a_t_e. If the window is in _N_o_r_m_a_l_S_t_a_t_e, its window is visible. If the window is in _I_c_o_n_i_c_S_t_a_t_e, its icon is visible. PPPPaaaaggggeeee 11114444 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) OOOOppppttttiiiimmmmaaaallll OOOOrrrrddddeeeerrrr ooooffff OOOOppppeeeerrrraaaattttiiiioooonnnnssss The application should eliminate unnecessary window mapping and unmapping, because they cause wasteful X server traffic, and because they may cause visible flashing on the screen. To do so: 1) If the end result of a series of operations is to be hidden, and if the window is currently visible, give the _h_i_d_e() call first. 2) If the end result of a series of operations is to be visible, and if the window is currently hidden, give the _s_h_o_w() call last. X11 states map into the ViewKit states as follows: IIIIccccoooonnnniiiiccccSSSSttttaaaatttteeee _v_i_s_i_b_l_e() && _i_c_o_n_i_c() NNNNoooorrrrmmmmaaaallllSSSSttttaaaatttteeee _v_i_s_i_b_l_e() && !_i_c_o_n_i_c() WWWWiiiitttthhhhddddrrrraaaawwwwnnnnIIIIccccoooonnnniiiiccccSSSSttttaaaatttteeee !_v_i_s_i_b_l_e() && _i_c_o_n_i_c() WWWWiiiitttthhhhddddrrrraaaawwwwnnnnNNNNoooorrrrmmmmaaaallllSSSSttttaaaatttteeee !_v_i_s_i_b_l_e() && !_i_c_o_n_i_c() To explore window states, see the demo program /_u_s_r/_s_h_a_r_e/_s_r_c/_V_i_e_w_K_i_t/_B_a_s_i_c/_w_i_n_d_o_w_S_t_a_t_e. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() KKKKNNNNOOOOWWWWNNNN DDDDEEEERRRRIIIIVVVVEEEEDDDD CCCCLLLLAAAASSSSSSSSEEEESSSS VkWindow, VkForkDoc, VkMsgWindow CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS VkApp, VkComponent KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS VkApp, VkDialogManager, VkMsgApp SSSSEEEEEEEE AAAALLLLSSSSOOOO VkComponent, VkApp, VkComponent, VkDialogManager, VkMsgApp _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Scheifler and Jim Gettys _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF PPPPaaaaggggeeee 11115555 VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) VVVVkkkkSSSSiiiimmmmpppplllleeeeWWWWiiiinnnnddddoooowwww((((3333xxxx)))) PPPPaaaaggggeeee 11116666